home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 076-100 / disk_077 / language.doc / draco.ref < prev    next >
Text File  |  1992-05-06  |  59KB  |  1,167 lines
  1.             Draco Quick Reference Guide
  2.  
  3.                Copyright 1983 by Chris Gray
  4.  
  5.  
  6. I. Using the compiler under AmigaDOS
  7.  
  8.     draco f1[.d] f2[.d] ... fn[.d]
  9.  
  10.     Each file is a separate compilation; they need not be related. If no
  11.     extension is given, then .d is assumed. For each file, if the
  12.     compilation is successful, a corresponding .r file is produced.
  13.  
  14. II. Using the assembler (not available in Amiga version)
  15.  
  16. III. Using the link editor
  17.  
  18.     The Draco linker has not yet been ported. Draco programs are currently
  19.     linked using BLink or ALink. See "Draco Other:Introduction" for some
  20.     details and the proper writeups for BLink and ALink for more details.
  21.     The description here of the CP/M-80 version of the Draco linker is kept
  22.     around so that if/when it is ported, the description can just be modified
  23.     as needed.
  24.  
  25.     link f1[.rel] f2[.rel] ... fn[.rel] fa.lib fb.lib ... fz.lib
  26.  
  27.     Each file is a .REL file produced by DAS or DRACO, a .LIB file produced
  28.     by DLIB, or a .PLD file produced by LINK. If no extension is given on a
  29.     file name, then .REL is assumed; thus libraries must have the .LIB given
  30.     explicitly. Flags can be interspersed with the file names. Each flag
  31.     starts with a minus sign (UNIX convention) and consists of several flag
  32.     letters, and perhaps one flag value. The recognized flags and their
  33.     meanings are:
  34.  
  35.     m - produce a map of the load address of the various procedures and
  36.         the addresses of all local and global variable groups. This map
  37.         is sent to a file whose base name is the same as that of the
  38.         resulting .COM file (see later) and whose extension is ".MAP".
  39.         The symbols will be sorted alphabetically.
  40.     a - produce a map file as above, but sort the symbols by their load
  41.         addresses. This is useful when debugging.
  42.     i - suppress the normal Draco initialization code. This option should
  43.         only be used by assembler programmers. Note: LINK allocates
  44.         data areas before code areas if -d is not specified. Thus, if
  45.         neither -s nor -d are specified, the first .REL file must not
  46.         have any file variables, and the first procedure in it must not
  47.         have any local variables. If either set of variables exist,
  48.         they will be first in the .COM file, and will be at the entry
  49.         point to the program. This option also prevents the standard
  50.         libraries TRRUN.LIB and TRCPM.LIB from being automatically
  51.         searched. (The 'TR' is from a previous name of the language.)
  52.     q - produce a program which will return to CP/M quickly. This is done
  53.         by using an alternate initialization section which leaves CP/M's
  54.         CCP untouched in memory, and which will simply return to CP/M
  55.         without doing a warm start. This flag should not be given when
  56.         linking programs which use CP/M's location 6 (pointer to warm
  57.         boot routine) to determine the top of available memory. The
  58.         pointer so returned does not take the CCP into account, and so
  59.         the resulting program will probably not run. A very smart program
  60.         could determine if it had been compiled with '-q' and subtract
  61.         the size of the CCP from the top-of-memory pointer. The standard
  62.         storage allocator does this by referencing the special symbols
  63.         '_DataEnd' and '_CodeEnd' which point to the ends of the data and
  64.         code portions of the final object file.
  65.     o - specifies the name for the resulting .COM file. The name must
  66.         immediately follow the 'o', with no intervening spaces or other
  67.         flags. If no explicit name is given, then the name is derived
  68.         from the name of the first .REL file in the parameter list.
  69.     c - specifies the first address to be used for program (code). The
  70.         value must follow immediately and is in hexadecimal. This option
  71.         is normally only useful for people who wish to produce .COM files
  72.         suitable for PROM burning. The default program start address is
  73.         0x100, which is the standard CP/M entry point.
  74.     d - specifies the first address to be used for data (variables). The
  75.         value must follow immediately and is in hexadecimal. This option
  76.         should be used for programs which have large data areas, or for
  77.         programs which are to be burned into PROMS. If no value is given,
  78.         then data areas are intermixed with code areas.
  79.     s - the linker is forced to take two passes for it's operation. The
  80.         first pass determines the total code size of the resulting
  81.         program, and the second pass does the actual linking, using a
  82.         data start address (as with the '-d' flag) just past the address
  83.         of the last byte of code. The 's' stands for small - the
  84.         resulting .COM file will be as small as possible (it will contain
  85.         only the code of the program) and the total space occupied will
  86.         be a minimum, since no gaps will exist. In linking with no flags
  87.         given, code and data will be intermixed, thus the data space will
  88.         occupy disk space in the .COM file
  89.     v - verbose. The linker prints out the names of the .REL and .LIB
  90.         files it is processing. This gives you something to watch when
  91.         linking a large program on slow disks.
  92.     p - requests that a .PLD file be produced representing the entire
  93.         program. This file is a machine readable map, in address order,
  94.         of all symbols loaded. The format is a 4 character hexadecimal
  95.         address, a space, the symbol name, and CR/LF for each symbol, and
  96.         an extra CR/LF at the end of the file. When such a PLD file is
  97.         given to LINK as input, the named symbols are assumed to pre-
  98.         exist at the given addresses. This could be because they are in
  99.         ROM or because they are in a program which has dynamically loaded
  100.         the program that is referencing them.
  101.  
  102.     The Draco linker provides partial support for a type of module, i.e. for
  103.     a fully independent package of routines with its own local variables,
  104.     it's own initialization and termination code, and a set of procedures
  105.     which are exported to its 'clients' or users. Most of this is provided
  106.     by the normal features of the Draco language. A module is written as a
  107.     single Draco source file, with its own local variables. Clients import
  108.     procedures from it in the normal way, using 'extern' declarations.
  109.  
  110.     The additional support provided by the linker works as follows. If a
  111.     procedure in a library is called, and the file which that procedure came
  112.     from contains another procedure called "_initialize", then the linker
  113.     will load "_initialize" and will generate code at the beginning of the
  114.     program to call it. Similarly, a routine called "_terminate" will be
  115.     automatically loaded and called at the end of the program (directly
  116.     returning to the system via "exit" or "SystemReset" will bypass the
  117.     termination call). There can be multiple occurrences of these special
  118.     symbols, so long as there is only one per source file.
  119.  
  120.     In the interests of portability, all versions of Draco will have
  121.     available a routine called "exit", which has a single integer parameter.
  122.     This routine will return directly to the host operating system. The
  123.     parameter passed is an error indicator, and should be 0 to indicate
  124.     successful execution. CP/M cannot make use of this returned error code,
  125.     but other systems can, so this facility is provided to simplify the
  126.     transportation of Draco programs among different systems.
  127.  
  128.     LINK's operation can involve one or two passes, each pass consisting of
  129.     a read of the .REL files and one or more reads of the .LIB files. The
  130.     second pass is necessary only if the '-s' flag is given or if the program
  131.     is too large to fit into the available memory. When operating in two-pass
  132.     mode, LINK can produce a final .COM file larger than the amount of memory
  133.     on the machine on which LINK is running. LINK will automatically switch
  134.     to two-pass mode whenever the available memory runs out.
  135.  
  136.     Libraries produced by DLIB have a directory at the front which indicates
  137.     where in the library all of the individual procedures can be found. LINK
  138.     loads only those procedures which have been referenced, and it will scan
  139.     the libraries several times if needed to resolve all references. If a
  140.     procedure is loaded which references file-level global variables, then
  141.     space for those variables is allocated, and all procedures from that
  142.     original source file will reference them. When running under CP/M 1.0,
  143.     random access is not supported, so the entire library is actually read
  144.     in, but under later versions of CP/M, random access is used to reduce the
  145.     amount of actual disk I/O done.
  146.  
  147.     If a given symbol is present in more than one of the libraries being
  148.     scanned, then it is loaded from the first library encountered after the
  149.     first reference to the symbol. All .REL files are scanned first, in the
  150.     order they appear on the LINK command, then all .LIB files are scanned,
  151.     in the order they appear on the LINK command. The entire set of .LIB
  152.     files is rescanned if further unresolved references occur. If the first
  153.     reference to a symbol comes from a library member, then the search for
  154.     that symbol starts with the remainder of that library and continues on
  155.     with later ones.
  156.  
  157.     Because of this strictly forward searching, the order of placement of
  158.     symbols in libraries can be important. If a procedure in a given source
  159.     file which is to be part of a library references another procedure in
  160.     that source file, then the referenced procedure should be forward
  161.     declared and appear LATER in the source file than its referencer. This
  162.     approach minimizes the number of library scans needed to resolve all
  163.     references. All of the standard libraries are set up this way.
  164.  
  165.     Unless the '-i' flag is given, LINK will automatically add the libraries
  166.     'TRRUN.LIB' and 'TRCPM.LIB' to the end of the set of libraries searched.
  167.     TRRUN.LIB contains the run-time system, including support needed by the
  168.     compiler, the I/O library and the utility library described later.
  169.     TRCPM.LIB is an interface library which provides interface routines to
  170.     all of the CP/M entry points. Entry point names are exactly as given in
  171.     the CP/M manuals - e.g. SetDMAAddress, ReadSequential, etc. Most simple
  172.     programs will not need any other libraries, and thus can be linked by
  173.     simply giving all of the .REL files. A program with only one source file
  174.     xxx.drc can thus be compiled and linked by:
  175.  
  176.     draco xxx
  177.     link xxx
  178.  
  179.     A program with source files p1.drc, p2.drc and p3.drc, which references
  180.     the CRT library can be fully compiled and linked by:
  181.  
  182.     draco p?
  183.     link p1 p2 p3 crt.lib
  184.  
  185.     For a final version, the '-s' flag should probably be given.
  186.  
  187. IV. Using the disassembler (not available in Amiga version)
  188.  
  189. V. Using the librarian (not available in Amiga version)
  190.  
  191. VI. Using the cross-referencer (not available in Amiga version)
  192.  
  193. VII. Draco source files
  194.  
  195.     Source files for the Draco compiler are either normal source files,
  196.     usually with an extension of .d, or are declaration include files,
  197.     usually with an extension of .g. Declaration include files can contain
  198.     only declarations (constant, type, external, variable), and the symbols
  199.     declared in them are called 'global', and are available to all procedures
  200.     in all source files which include that particular include file.
  201.  
  202.     Normal source files contain, in the order given:
  203.  
  204.     - 0 or more include file references. These must start in the first
  205.         column of the first line, and consist of a backslash (\) or
  206.         number sign (#) followed by the name of the include file being
  207.         referenced. Several such references may occur, one per line,
  208.         with no intervening spaces or comments. When a program consists
  209.         of more than one source file, each of the source files will
  210.         usually have the same set of include file references. The link
  211.         editor requires that the 'global' variables be consistent among
  212.         all .r files being linked. .r files being put into libraries
  213.         may not have any 'global' variables.
  214.  
  215.     - declarations. These declarations are called 'file' declarations,
  216.         and are available to all procedures in that particular source
  217.         file. Short Draco programs, consisting of only one source file,
  218.         will not have any 'global' declarations - the 'file' declarations
  219.         will play that role. In larger programs, 'file' declarations are
  220.         still useful, in that procedures associated with a given portion
  221.         of a program can be assembled in one file, and any declarations
  222.         private to those procedures can be 'file' declarations in that
  223.         file, and thus will not be accessible to any other procedures.
  224.         Also, 'file' declarations are common in files which are to be
  225.         used as part of a library, since any 'file' variables will be
  226.         allocated (assigned real memory addresses) by the link-editor
  227.         whenever a routine from that file is referenced.
  228.  
  229.     - procedures. Each procedure can have it's own set of local
  230.         declarations (it's parameters are assumed to be part of that
  231.         set). These declarations are accessible only within that
  232.         procedure, and the values of any variables are not preserved
  233.         between activations of the procedure. Procedures defined in a
  234.         source file are considered to be declared for the remainder of
  235.         that source file. If circular referencing of procedures is
  236.         required, then a 'file' level extern declaration of the procedure
  237.         can be given before the procedure is used, and, so long as that
  238.         declaration is consistent with the final definition, the compiler
  239.         will not complain. Because of the compiler's requirement that
  240.         all symbols be declared before they are used, the simplest
  241.         arrangement of source files is that which puts the lowest-level
  242.         routines first, and the highest-level routines (those which call
  243.         the lower-level ones) last. Thus, short programs consisting of
  244.         only one source file will normally put procedure 'main' last.
  245.         (All Draco programs must have a procedure 'main', since the
  246.         initialization code starts program execution by calling 'main'.)
  247.  
  248.         In keeping with a highly readable convention used by some UNIX
  249.         programmers, it is suggested that all 'global' and 'file'
  250.         symbols begin with a capital letter, and all local symbols
  251.         begin with a small letter (other than constants). In keeping
  252.         with this convention the names of all routines in all libraries
  253.         supplied with Draco begin with a capital letter. Even though
  254.         procedure definitions are technically 'file' declarations, such
  255.         procedures, unless they are to be part of an externally
  256.         available library, should have names beginning with small
  257.         letters.
  258.  
  259.         Draco takes a different approach to scope than many standard
  260.         algorithmic languages. Languages such as Pascal, Algol68, etc.
  261.         allow the declaration of an identifier, at an inner scope level,
  262.         which is already declared at an outer scope level. For the
  263.         duration of that scope, the new, inner, declaration masks the
  264.         outer declaration so that the outer meaning of the identifier
  265.         is not available. In Draco, it is illegal to attempt to declare
  266.         an identifier which already exists, regardless of the scope
  267.         levels of the declarations (Draco only has 3 levels anyway -
  268.         global, file and local). Several procedures can declare the same
  269.         identifier locally (names such as 'i', 'p', 'n', etc. are quite
  270.         common), but they cannot declare a name which exists at either
  271.         the global or file level. Similarly, at the file level, a name
  272.         cannot be used which is already in use at the global level. This
  273.         approach is used so as to eliminate the problems arising from
  274.         accidentally masking an outer meaning in a situation which uses
  275.         that outer meaning, but also declares a similar, inner meaning.
  276.         This situation can result in bugs which are very difficult to
  277.         detect. If the naming convention suggested above is used, little
  278.         inconvenience will occur. Also, since Draco imposes no limit on
  279.         the length of identifiers, there should be no problem in choosing
  280.         meaningful ones.
  281.  
  282. VIII. Declarations
  283.  
  284.     Declarations in Draco can be of constants, types, variables or external
  285.     procedures.
  286.  
  287.     Constant declarations consist of the type, followed by the identifiers,
  288.     along with an '=' and their value. Constants can be numeric (signed or
  289.     unsigned), single character, or 'chars' values. In keeping with a highly
  290.     readable convention used on UNIX systems, it is suggested that the names
  291.     of constants be fully capitalized. Example constant declarations:
  292.  
  293.     uint MAX_LENGTH = 1000,
  294.          ENTRY_COUNT = 10;
  295.     char BEL = '\(7)', BS = '\b', LETTER_F = 'f';
  296.     *char AUTHOR = "Sam Spade";
  297.     unsigned 255 LIMIT = 255 - 1;
  298.  
  299.     The values used for constants can be any expression whose value can be
  300.     determined at compile time by the compiler. This can include conditional
  301.     expressions, so long as the conditions are known at compile time.
  302.  
  303.     Type declarations consist of the word 'type', followed by the names of
  304.     the new types, each followed by '=' and the type's definition. The
  305.     various kinds of types in Draco are as follows:
  306.  
  307.     - signed numeric types. These are specified by the word 'signed',
  308.         followed by a constant expression giving the upper bound on the
  309.         positive values allowed. The negative values have a similar
  310.         limit (one less for 2's complement machines). The maximum value
  311.         of the limit will vary from machine to machine and possibly from
  312.         version to version of the compiler. All versions will allow at
  313.         least 'signed 32767'. In programs where execution time must be
  314.         minimized, the programmer should use numeric types with the
  315.         smallest possible range. This allows the compiler to generate
  316.         more efficient code for CPU's which do some types of arithmetic
  317.         better than others.
  318.  
  319.     - unsigned numeric types. These are specified by the word 'unsigned',
  320.         followed by a constant expression giving the upper bound on the
  321.         values allowed (the lower bound is 0). Signed and unsigned values
  322.         can be mixed in arithmetic operations. The two kinds of values
  323.         can be compared for equality, but not for magnitude (they use the
  324.         same bit pattern for different values).
  325.  
  326.     - enumerated types. These are specified by the word 'enum', followed
  327.         by an open brace ({), followed by a list of the named values of
  328.         this type, followed by a close brace (}). The values named in the
  329.         list are the only allowed values of this type. They can be
  330.         compared (all comparisons are meaningful), subtracted (the result
  331.         is an unsigned numeric), and can have a numeric added to or
  332.         subtracted from them (the result is another value of the same
  333.         enumerated type). This kind of type is usually used for flag
  334.         values, where the flag can take on a limited set of values. A
  335.         sample enumerated type:
  336.  
  337.         enum {c_red, c_yellow, c_blue, c_black, c_white}
  338.  
  339.     - pointer types. These are specified by an '*' preceding the type
  340.         which is to be pointed to. Thus, '*int' is a type specification
  341.         meaning 'pointer to integer'. In the language's single exception
  342.         to the requirement that all identifiers be declared before they
  343.         can be used, the pointed to type can be an undeclared symbol,
  344.         which is assumed to be an as-yet undeclared type, which must be
  345.         declared before the end of the current set of declarations. This
  346.         rule relaxation is used to allow the construction of circularly
  347.         referencing structures. Pointer values can be compared,
  348.         subtracted (as long as the values are of the same pointer type),
  349.         and can have a numeric value added to or subtracted from them.
  350.         Unlike similar operations in the 'C' language, the value being
  351.         added or subtracted is not multiplied by the size of the
  352.         pointed-to type. Pointer values are usually generated via the '&'
  353.         address-of operator, or by using a 'chars' constant, which is of
  354.         type *char. The predefined value 'nil' is compatible with all
  355.         pointer types.
  356.  
  357.     - array types. These are specified by a left square bracket ([),
  358.         followed by a list of constant expressions giving the size of the
  359.         array in that dimension, followed by a right square bracket (]),
  360.         followed by the type of the array elements. There is no limit on
  361.         the number of dimensions of an array, but the user must keep in
  362.         mind the amount of memory occupied by the array as compared to
  363.         the amount of memory available on the computer system. Arrays
  364.         are stored in row-major order, i.e. when scanning along an array
  365.         in memory, the last index varies most frequently. Array values
  366.         can be assigned. Sample array types:
  367.  
  368.         [MAX_NAME_LENGTH + 1] char
  369.         [M, N, P] int
  370.         [BLOCK_COUNT] [BLOCK_LEN] unsigned 32
  371.  
  372.     - structure types. These are specified by the word 'struct', followed
  373.         by a left brace bracket ({), followed by the types and names of
  374.         the fields of the structure, followed by a right brace bracket
  375.         (}). Unlike some other languages, Draco does not allow field
  376.         names to be re-used; all must be unique. The easiest way to do
  377.         this is to follow yet another highly readable UNIX convention
  378.         which names all fields of a structure as a short abbreviation of
  379.         the structure name (1 - 3 letters), followed by an underscore (_)
  380.         and the mnemonic name of the field. Like array types, structure
  381.         types can be assigned. Some structure declarations:
  382.  
  383.         type
  384.             ProcessState_t = struct {
  385.             uint st_programCounter, st_stackPointer;
  386.             [8] uint st_registers;
  387.             byte st_statusRegister;
  388.             },
  389.  
  390.             Process_t = struct {
  391.             int pr_priority;
  392.             *Process_t pr_parent, pr_children, pr_nextSibling;
  393.             ProcessState_t pr_state;
  394.             *ProcessQueue_t pr_waitQueue;
  395.             },
  396.  
  397.             ProcessQueue_t = struct {
  398.             *ProcessQueue_t pq_next;
  399.             *Process_t pq_this;
  400.             };
  401.  
  402.     - union types. Union types are declared exactly like structure types
  403.         except that the word 'union' replaces the word 'struct'. Union
  404.         types are similar to unions in 'C', in that they specify a type
  405.         which is a set of types. The space allocated for a value of a
  406.         union type is the maximum of the spaces needed for the various
  407.         member types in the union. The programmer informs the compiler
  408.         which of the member types is currently active by selecting the
  409.         member type, exactly as a field of a structure is selected, when
  410.         the union value is referenced or assigned to as other than the
  411.         union type. Union types are useful when constructing networks of
  412.         nodes, and the nodes are of differing natures, but all are
  413.         pointed to by other nodes. The alternative of having separate
  414.         pointers for each possible node type is very wasteful of memory.
  415.         Sample union type: (this one from a railroad simulation)
  416.  
  417.         type
  418.             Track_t = union {
  419.             int tr_straight;    /* straight track option */
  420.             struct {        /* turnout option */
  421.                 int trn_length;
  422.                 bool trn_open;
  423.                 bool trn_isRight;
  424.             } tr_turnout;
  425.             };
  426.  
  427.     - procedure types. These types are declared similarly to actual
  428.         procedure headers, except that no procedure name occurs, no
  429.         machine specific options (e.g. 'nonrec') can occur, and the names
  430.         of the parameters are required, but are irrelevant. Procedure
  431.         values can be compared for equality, assigned, and called. Sample
  432.         procedure types:
  433.  
  434.         proc (int a, b)int
  435.         proc (proc (char c)void putChar; *char charsPtr)void
  436.         proc ([12]**int x, y)[12]**int
  437.  
  438.     - operator types. This kind of type is Draco's (somewhat limited) way
  439.         of being an extensible language. Syntactically an operator type
  440.         consists of an open parenthesis, a string constant, a comma, a
  441.         base type, a comma, a numeric constant and a close parenthesis.
  442.         The string constant is a prefix which is used to build the names
  443.         of the procedures that the compiler will generate calls to in
  444.         order to do operations on values of this new type. The base type
  445.         is the type that is the underlying representation of this new
  446.         type, and the numeric constant is a set of 16 bits, indicating
  447.         which operations are enabled for this type. Operator types will
  448.         be explained in a later section.
  449.  
  450.     Types in Draco can be combined in arbitrary ways. The only
  451.     limitations imposed by the compiler are those inherent in the sizes
  452.     of the type table and the type information table. The question of
  453.     type equivalence is answered in Draco in the following way: two
  454.     types are equivalent if they are equivalently constructed from
  455.     equivalent component types. The determination of type equivalence is
  456.     done while the compiler is parsing the type specification. Thus, in
  457.     the following:
  458.  
  459.         [12] int a;
  460.         [10 + 4 / 2] int b;
  461.  
  462.     'a' and 'b' will have the same type. The type of 'b' is equivalent
  463.     to the type of 'a', and so will BE the type of 'a'. If a type is
  464.     given a name via a type declaration, however, then that type is
  465.     unique and is not equivalent to any other named type. Thus, if we
  466.     declare:
  467.  
  468.         type T1 = [10] int,
  469.          T2 = [10] int;
  470.         T1 a;
  471.         T2 b;
  472.         [10] int c;
  473.  
  474.     Types T1 and T2 are not equivalent, and 'a' and 'b' cannot be
  475.     assigned to one-another. Both can be assigned to or from 'c',
  476.     however, else there would be no way to generate values of named
  477.     types. This scheme is an attempted compromise between the need for
  478.     usability of named types, and the desire to have the compiler
  479.     protect us from mistakes when two named types just happen to have
  480.     equivalent definitions. Signed or unsigned numeric types which are
  481.     named are always compatible with other named or unnamed numeric
  482.     types, whether equivalent or not.
  483.  
  484.     The following types are supplied predefined:
  485.  
  486.         int - signed numeric using the standard fully supported word
  487.         size on the host processor
  488.         short - smaller sized signed value (often 8 bit)
  489.         long - longer sized signed value (often 32 bit)
  490.         uint - unsigned numeric, same size as int
  491.         ushort - unsigned numeric, same size as short
  492.         ulong - unsigned numeric, same size as long
  493.         byte - unsigned numeric, one byte long (8 bits)
  494.         char - enumeration type of all 256 character values
  495.         bool - enumeration type consisting of 'false' and 'true'
  496.  
  497.     Most programs can safely use types 'int' and 'uint', since they will
  498.     always be at least 16 bits long. The careful programmer will usually
  499.     use his/her own signed and unsigned types, however, so that the
  500.     reader is always aware of the range of possible values, and so that
  501.     compilers can optimally decide the implemented size of variables
  502.     (which may vary from processor to processor).
  503.  
  504.     Variable declarations consist of the type (either named or explicit)
  505.     followed by a comma separated list of identifiers. This format is
  506.     similar to that used for constants, but combining the two is not
  507.     advised, since doing so can be confusing.
  508.  
  509.     External procedure declarations consist of the word 'extern' followed
  510.     by a list of procedure headers, complete with procedure name, parameter
  511.     types and names, and result type.
  512.  
  513. IX. Procedures
  514.  
  515.     Each Draco procedure definition begins with the word 'proc', followed
  516.     by any special machine dependent modifiers, followed by the name of the
  517.     procedure, followed by a procedure header, followed by a colon, followed
  518.     by the body of the procedure and a final terminating word, 'corp'. A
  519.     procedure header consists of '(', optional parameter declarations, ')',
  520.     and the result type (or 'void' for procedures which don't return a
  521.     result). Note that the parentheses are required, even if no parameters
  522.     are declared. Parameter declarations are just like variable declarations.
  523.  
  524.     Unlike Pascal and C, Draco provides a way for arrays of differing sizes
  525.     to be passed to a common procedure. An array parameter can use an
  526.     asterisk (*) for the size of one or more of its dimensions, instead of
  527.     the normal constant expression. When such a procedure is called, the
  528.     compiler will automatically pass the true size of the dimensions of the
  529.     passed array along with the array. These true sizes can be determined
  530.     inside the procedure via the 'dim' construct. Note that this method can
  531.     only be used for parameter arrays, and can only be used for top level
  532.     arrays (e.g. if the parameter is an array of arrays, then only the top-
  533.     level array can have '*' sizes).
  534.  
  535.     If the procedure is to return a result, the type placed between the
  536.     closing ')' of it's header and the following ':' is the type expected
  537.     by the compiler. Conversions among various numeric types are allowed
  538.     here as elsewhere. The result is returned by placing it at the end of
  539.     the procedure's body, just before the closing 'corp'. There must not be
  540.     a semicolon after the result, since the compiler uses the semicolon as
  541.     a signal that the previous unit should have been a statement. As a sample
  542.     procedure, here is the old standard, "Towers of Hanoi":
  543.  
  544.     proc hanoi(int n; *char from, to, using)void:
  545.  
  546.         if n > 0 then
  547.         hanoi(n - 1, from, using, to);
  548.         writeln("Move disk ", n, " from peg ", from, " to peg ", to);
  549.         hanoi(n - 1, using, to, from);
  550.         fi;
  551.     corp;
  552.  
  553.     A standard procedure with a result:
  554.  
  555.     proc minimum([*] int a)int:
  556.         int i, min;
  557.  
  558.         min := a[0];
  559.         for i from 1 upto dim(a, 1) - 1 do
  560.         if a[i] < min then
  561.             min := a[i];
  562.         fi;
  563.         od;
  564.         min
  565.     corp;
  566.  
  567. X. Statements in Draco
  568.  
  569.     Draco is a fairly standard programming language, along the lines of
  570.     Pascal, C, and Algol. Where several statements are allowed, they are
  571.     separated by semicolons (the semicolon is a separator, not a terminator).
  572.     The standard statement forms in Draco are:
  573.  
  574.     - assignment statement. This is the usual, consisting of the destination,
  575.     a ':=', and the source expression.
  576.  
  577.     - procedure call statement. This consists of the procedure's name (or an
  578.     expression yielding a procedure), followed by the procedure's
  579.     parameters, enclosed in parentheses. The parentheses must be present,
  580.     even if the procedure has no parameters (this makes it very clear
  581.     when something is being called - useful for procedures such as random
  582.     number generators which have no parameters but return a result).
  583.     The parameters passed must be compatible with those specified in
  584.     the defining procedure header, in terms of both type and number.
  585.  
  586.     - if statements. If statements in Draco are syntactically identical to
  587.     if statements in Algol68. The simplest form consists of the word
  588.     'if', followed by an expression of type 'bool', followed by the word
  589.     'then', followed by a sequence of statements to be executed when the
  590.     bool yields 'true', followed by the word 'fi'. An 'else' clause,
  591.     which is executed when the bool yields 'false', can be placed between
  592.     the 'true' statements and the 'fi'. An 'else' clause consists of the
  593.     word 'else' and a sequence of statements. As in Algol68, alternate
  594.     conditions, consisting of the word 'elif', a bool expression, the
  595.     word 'then', and a statement sequence, can be placed between the
  596.     first statement sequence and the 'else' (or 'fi' if there is no
  597.     'else'). In that case, the conditions are evaluated one at a time,
  598.     until one is found that yields 'true'. The corresponding statement
  599.     sequence is then executed. Only if no condition yields 'true' will
  600.     the 'else' statements be executed. When a condition has yielded
  601.     'true', no more conditions will be evaluated. As an example,
  602.  
  603.         if a then
  604.         b
  605.         elif c then
  606.         d
  607.         elif e then
  608.         f
  609.         else
  610.         g
  611.         fi
  612.  
  613.     is equivalent to
  614.  
  615.         if a then
  616.         b
  617.         else
  618.         if c then
  619.             d
  620.         else
  621.             if e then
  622.             f
  623.             else
  624.             g
  625.             fi
  626.         fi
  627.         fi
  628.  
  629.     The advantage of the 'elif' form is fairly obvious - it has far less
  630.     indentation for the same logic.
  631.  
  632.     The standard if statement is the basis for the conditional
  633.     compilation feature of the Draco compiler. If the condition for an
  634.     if statement can be evaluated at compile time, then no code is
  635.     generated for the if statement, and code for only one of the branches
  636.     is generated. This feature is not as flexible as that provided by
  637.     full macro preprocessors, but it has the advantage that the compiler
  638.     always checks all branches for correct syntax and semantics, thus the
  639.     programmer can be sure that changing the flag value controlling the
  640.     conditional compilation will not cause the program to stop compiling.
  641.     (With macro pre-processors, and conditional inclusion, as supported
  642.     by most C compilers, the compiler does not even see the code which
  643.     has been conditioned out.) By including conditional compilation
  644.     in the compiler, rather than requiring a separate pre-processor,
  645.     compilation times for Draco programs can be significantly less.
  646.     One common use for conditional compilation is that of including
  647.     debugging statements, dependent on a global debugging flag. E.g.
  648.  
  649.         bool DEBUG = false;
  650.         ...
  651.         if DEBUG then
  652.         writeln(DebugOut; "We got to this point, key values are:");
  653.         ...
  654.         fi;
  655.  
  656.     In situations like this, the Draco compiler will generate no code at
  657.     all for the entire if statement. If the DEBUG flag is set to 'true'
  658.     instead, then the debugging code will appear, but there will still be
  659.     no code to actually test DEBUG (DEBUG doesn't even exist). For more
  660.     complex debugging, the DEBUG flag can be a number, specifying the
  661.     level of debugging required. Another common use of conditional
  662.     compilation is to have one source file which can produce two or more
  663.     different versions of a program, depending on one or more flags.
  664.  
  665.     - while statements. The standard while statement consists of the word
  666.     'while', followed by a bool expression, followed by the word 'do',
  667.     followed by a sequence of statements (the loop body), followed by
  668.     the word 'od'. Draco allows an extension of this form, in which a
  669.     sequence of statements can be placed between the 'while' and the
  670.     bool expression. This extension allows the same 'while' construct to
  671.     serve as beginning, middle and end exit loops. E.g.
  672.  
  673.         while
  674.         write("Enter command: ");
  675.         command := getCommand();
  676.         command ~= HALT
  677.         do
  678.         processCommand(command);
  679.         od;
  680.  
  681.     - for statements. The for statement is the standard way in Draco of
  682.     iterating over a fixed sequence of values. It is similar to the
  683.     for statements in most programming languages. It consists of the
  684.     word 'for', followed by the name of the variable to use as an index
  685.     variable, followed by the word 'from' and an expression giving the
  686.     start of the range, optionally followed by the word 'by' and an
  687.     expression giving the step amount, followed by either the word
  688.     'upto' or the word 'downto' and an expression giving the end of the
  689.     range, followed by the word 'do', followed by a statement sequence,
  690.     and finally, the word 'od'.
  691.  
  692.     In Draco, the direction of the loop (increasing or decreasing) is
  693.     set at compile time, by the selection of 'upto' or 'downto'. If the
  694.     'by' part is omitted, then either +1 or -1, whichever is appropriate,
  695.     is used. The for loop terminates when the index variable attains the
  696.     last possible value between the two limits (inclusive). Thus we have
  697.     the loop
  698.  
  699.         for i from 1 by 5 upto 13 do
  700.         ...
  701.         od;
  702.  
  703.     stepping 'i' through the values 1, 6, and 11. The index variable can
  704.     be numeric (signed or unsigned), an enumeration value, or a pointer
  705.     value. The limits must be compatible with the index variable, and
  706.     the 'by' value, if present, must be numeric. Thus we can have a loop
  707.     which steps through every second letter of the alphabet:
  708.  
  709.         for ch from 'a' by 2 upto 'z' do
  710.         ...
  711.         od;
  712.  
  713.     Most programs which do a lot of computation have a lot of for loops
  714.     in them (fancy compilers are an exception). Thus, it is beneficial
  715.     if the compiler can generate fairly fast code for for loops. The
  716.     Draco compiler does a number of fancy tricks with for loops. Because
  717.     of this, it is important that none of the assumptions made by the
  718.     compiler are broken. Thus, the program should never attempt to assign
  719.     a value to the for index variable within the for loop. (A later
  720.     version of the compiler may be able to flag such usages as errors.)
  721.  
  722.     - case statements. Case statements in Draco are similar to those in
  723.     many languages; they are of the variety where the individual
  724.     alternatives being selected among are an explicit part of the case
  725.     statement. A default alternative is also available. The syntax is as
  726.     follows: the word 'case'; followed by the expression being used as a
  727.     selector; followed by several alternatives, each consisting of 1 or
  728.     more alternative index values given as the word 'incase', a constant
  729.     expression, and a colon. Each alternative then has a body, which is
  730.     a sequence of statements to be executed when that alternative is
  731.     selected. The entire case statement is terminated by the word 'esac'.
  732.     The default case, if present, can occur anywhere among the
  733.     alternatives, and consists of the word 'default' and a colon,
  734.     followed by the statements of the default case. The alternative index
  735.     values can be a pair of values separated by '..', in which case all
  736.     values between the two (inclusive) are used. The index expression
  737.     can be of any numeric or enumerated type. The alternative index
  738.     values must be compatible with the index expression. A sample case
  739.     statement:
  740.  
  741.         case ch
  742.         incase 'a':
  743.         incase 'A':
  744.         writeln("It was an A.");
  745.         incase 'b' .. 'd':
  746.         incase 'B' .. 'D':
  747.         x := y;
  748.         y := z;
  749.         default:
  750.         flag := true;
  751.         esac;
  752.  
  753.     The various Draco compilers will use different code sequences to
  754.     handle case statements. At least two forms will probably be
  755.     supported - one form which uses the index expression as a direct
  756.     index in a (perhaps sparse) table of code addresses, and one form
  757.     which uses a binary search through a sorted table of the alternative
  758.     index values. The appropriate form will be selected by the compiler,
  759.     based on the range and number of alternative index values.
  760.  
  761.     - I/O statements are discussed in a separate section later.
  762.  
  763.     - the 'free' construct, which can be applied to any value of a pointer
  764.     type, returns the storage pointed to to the storage allocator. That
  765.     storage must have been previously allocated by using 'new'. 'free' is
  766.     a statement since it returns no result.
  767.  
  768.     - the 'pretend' type-cheating construct can be used as a statement
  769.     if the type being forced is 'void'. This form is used to throw
  770.     away a value, usually from a procedure, which is not needed.
  771.  
  772.     - the 'error' construct, which accepts a parenthesized string constant
  773.     as its argument, simply uses that string as the text of an error
  774.     message to print AT COMPILE TIME. This construct is useful for
  775.     putting consistency checks into code. For example, if a program has
  776.     been written with the assumption that "IDENTIFIER"s fit in one byte,
  777.     then the following check, done somewhere in the program, would be
  778.     appropriate:
  779.  
  780.         if range(IDENTIFIER) > 255 then
  781.         error("IDENTIFIER range must be <= 255");
  782.         fi;
  783.  
  784.     Then, when someone comes along later and changes the definition of
  785.     the IDENTIFIER numeric type, if the type is made bigger than
  786.     'unsigned 255', a compile time error message will be produced when
  787.     compiling the file containing the above check. Near the check would
  788.     be a good place to put comments saying why the limitation exists.
  789.  
  790.     - some machine dependent constructs are formulated as statements.
  791.  
  792. XI. Expressions in Draco
  793.  
  794.     Most small processors are more efficient at doing 8 bit operations then
  795.     they are at doing 16 or 32 bit operations. Because of this, the Draco
  796.     compiler will normally attempt to use the smallest possible size for
  797.     a given numeric type. One result of this is that the operands to an
  798.     operator may not be of the same size. In such cases, the compiler will
  799.     expand the smaller value (doing sign-extension on signed values) and do
  800.     the operation in the larger size. The one exception to this rule involves
  801.     the shift operators - the operation is always done in the size of the
  802.     value being shifted (the left operand). Also, the type of numeric
  803.     constants will be overridden by any non-constant operand, so long as
  804.     their value will fit in that size. If both operands are constants, the
  805.     larger type will be used as the result type.
  806.  
  807.     Similarly, the result of an operation can depend on whether that
  808.     operation is done using signed or unsigned arithmetic. In cases where
  809.     one operand to an arithmetic operator is signed and the other is
  810.     unsigned, the operation is done as a signed operation, and the result
  811.     is considered to be signed. This only affects the result for the
  812.     division and remainder operations. Note that this rule is opposite to
  813.     that of C, which would yield an unsigned result. This can be thought of
  814.     as follows: in C, the normal numeric type is signed, while in Draco, the
  815.     normal numeric type is unsigned. In either language, any ocurrence of
  816.     a non-normal value forces non-normal operation and result. This choice
  817.     in Draco is likely to be contentious - the reasoning is that most numbers
  818.     used in most programs are unsigned. I personally find C's habit of
  819.     reserving '-1' as an error flag to be quite disgusting. As with size, the
  820.     signedness of a constant is ignored unless both operands are constants.
  821.  
  822.     Draco has a fairly large set of operators. These include the familiar
  823.     arithmetic operators of addition, subtraction, etc., along with a full
  824.     set of bit operators (and, xor, etc.), and a few special operators. The
  825.     operators are at various levels of priority, meaning that a higher
  826.     priority operator will be evaluated before a lower priority one, unless
  827.     there are parentheses explicitly governing the order of evaluation. This
  828.     reflects the usual view that multiplication comes before addition, etc.
  829.     Draco also has the usual constructs for calling functions, indexing
  830.     arrays, selecting fields of structures, etc. These are included in the
  831.     following table, to indicate their position in the precedence scheme.
  832.     The operators and constructs, in order of decreasing precedence are:
  833.  
  834.     ----------
  835.  
  836.     * - postfix dereferencing operator. This operator is postfix in
  837.         Draco, rather than prefix as in C, so that there is never any
  838.         ambiguity about the order in which the various constructs are to
  839.         be applied (consider *a[i] in C, which is either a[i]* or a*[i]
  840.         in Draco (I can never remember how C evaluates these)).
  841.  
  842.     [] - postfix array indexing. Array indexing is 0-origin in Draco,
  843.         i.e. the first element of an array has index 0. The compiler will
  844.         attempt to be efficient with indexing, but most microprocessors
  845.         have little direct support for array indexing, so if the
  846.         application is critical in terms of CPU time or program size, it
  847.         may be necessary to use pointer arithmetic instead of array
  848.         indexing. Values used for indexing can be of any numeric or
  849.         enumeration type.
  850.  
  851.     . - field selection. Field selection in Draco is fairly efficient,
  852.         usually requiring little, if any, extra machine code. The same
  853.         notation (structure '.' field-name) is used to select the current
  854.         form from a union type value.
  855.  
  856.     () - function calling. Function calls are identical to procedure
  857.         calls, except that they return a value. The function to be called
  858.         can be the result of an expression. (E.g. many versions of UNIX
  859.         contain an array of structures of procedures, which is used to
  860.         direct I/O calls based on the device being accessed (the array
  861.         index), and the particular function requested.)
  862.  
  863.     ----------
  864.  
  865.     & - prefix address-of operator. This operator takes the address of
  866.         it's operand. The type of the value generated is 'pointer-to-X',
  867.         where 'X' is the type of the operand. This operator cannot be
  868.         applied to expressions which do not have an inherent address,
  869.         e.g. '&(a + 1)' will not work, but '&a[i].name[j]' will. In
  870.         general, these constructs are arranged in Draco in such a way
  871.         that if you need brackets to express it, it's probably illegal.
  872.  
  873.     ----------
  874.  
  875.     ~ - prefix bitwise complement operator. This and the other bit
  876.         operators can only be applied to numeric values.
  877.  
  878.     ----------
  879.  
  880.     & - bitwise and operator.
  881.  
  882.     >< - bitwise exclusive-or operator.
  883.  
  884.     << - logical left shift operator. In both shift operators, the left
  885.         operand must be an unsigned numeric, while the right operand can
  886.         be any numeric. The operation and result are done using the size
  887.         of the left operand.
  888.  
  889.     >> - logical right shift operator.
  890.  
  891.     ----------
  892.  
  893.     | - bitwise inclusive-or operator.
  894.  
  895.     ----------
  896.  
  897.     | - prefix numeric absolute value operator. This, and other
  898.         arithmetic operators, can only be applied to numeric values.
  899.         (Exceptions for binary + and - are listed there.) Both the
  900.         absolute value and negation unary operators always yield a
  901.         signed type, regardless of the signedness of their operand.
  902.  
  903.     - - prefix numeric negation operator.
  904.  
  905.     + - prefix numeric do-nothing operator. This operator is included so
  906.         that forms like '+0' can be allowed.
  907.  
  908.     ----------
  909.  
  910.     * - multiplication operator.
  911.  
  912.     / - division operator.
  913.  
  914.     % - remainder operator.
  915.  
  916.     ----------
  917.  
  918.     + - addition operator. In addition to numeric operands, one
  919.         operand can be of an enumeration or pointer type. The resulting
  920.         value will be of the same type, incremented by the other,
  921.         numeric, operand. Unlike C, which pre-multiplies the numeric
  922.         value by the size of the pointed-to type, Draco doesn't modify
  923.         the numeric value at all.
  924.  
  925.     - - subtraction operator. Similar to incrementing a pointer or
  926.         enumeration value, these values can be decremented by using them
  927.         as the left-hand operand in subtraction. Two enumeration or
  928.         pointer values of the same type can also be subtracted, yielding
  929.         an unsigned numeric value.
  930.  
  931.     ----------
  932.  
  933.     >, <, >=, <=, =, ~= - comparison operators. Most values in Draco can
  934.         be compared. For some comparisons, only the equality comparisons
  935.         (= and ~=) are meaningful. For example, comparing a signed
  936.         numeric with an unsigned numeric can yield two different results,
  937.         depending on whether a signed or unsigned comparison is used.
  938.         Because of this, the compiler will not allow a signed value to be
  939.         compared with an unsigned value with other than = or ~=. The
  940.         values being compared must be of compatible types. Structure and
  941.         array types cannot be compared, since these types might contain
  942.         internal gaps due to alignment requirements, and the contents of
  943.         these gaps is undefined.
  944.  
  945.     ----------
  946.  
  947.     Along with the capability of conditional compilation provided by the
  948.     if statement, the Draco compiler attempts to evaluate expressions at
  949.     compile-time, so that they need not be evaluated at run-time. If both
  950.     operands to an operator can be evaluated at compile time, then the
  951.     operation is done at compile time, producing a constant. The evaluation
  952.     is done using the highest precision supported by the compiler. The
  953.     nature of the evaluation will be the same as if it was done at run-time,
  954.     i.e. mixing signed and unsigned values will yield a signed result, etc.
  955.     This facility is used in all places where constants appear, e.g. in
  956.     array declarations, signed/unsigned declarations, case statement
  957.     alternative index values, etc.
  958.  
  959.     There are several forms of expressions in Draco which do not involve
  960.     actual operators. These include the boolean 'and', 'or' and 'not'
  961.     operations. These are not classed with the normal operators, since they
  962.     are actually language constructs instead. Both 'and' and 'or' will not
  963.     evaluate their right-hand operand if the value of the left-hand operand
  964.     is sufficient to determine the result. This is known as 'short-circuit-
  965.     evaluation', or the McCarthy form of the 'and' and 'or' operators. There
  966.     is no exclusive-or operation for bools, but the same result can be
  967.     achieved using the ~= operator, which can be applied to bool values.
  968.  
  969.     Draco also allows conditional expressions - the if expression and the
  970.     case expression. These forms are identical to their statement forms,
  971.     except that the various statement sequences used as their alternatives
  972.     must end with an expression, which is the result for that alternative.
  973.     Also, if expressions must have an else part, since they must yield a
  974.     result in all cases. The same feature which allows if statements to be
  975.     used for conditional compilation allows the use of if expressions in
  976.     constant expressions, so long as the conditions and all alternative
  977.     values are themselves constant expressions.
  978.  
  979.     The unwise programmer can 'type cheat' (convince the compiler to allow
  980.     him to do things which he would not normally be allowed to do) by
  981.     misusing union types. In the hope of preventing this, Draco has an
  982.     explicit construct for type cheating. It uses the word 'pretend'. The
  983.     form 'pretend(expr, type)' instructs the compiler to consider 'expr' to
  984.     be of type 'type', regardless of what it thinks the type must be. As a
  985.     special case, 'type' can be 'void', in which case the value of 'expr' is
  986.     simply discarded (this action, called voiding, is done automatically by
  987.     most C compilers, often resulting in programming errors, since it is
  988.     easy to do it unintentionally). The pretend construct should be used
  989.     with great care, since some values cannot possibly be of some types. For
  990.     example, what is supposed to happen in something like 'pretend(x + y,
  991.     [10] int)'? A more innocuous form of the pretend construct uses the word
  992.     'make' instead of the word 'pretend'. This form requests that the
  993.     compiler convert the given expression to the given type. This form will
  994.     only allow those conversions which make sense. 'make' is normally used
  995.     to expand a short value to a longer form, to force an operation to be
  996.     in a longer form (e.g. to force 16 bit arithmetic on 8 bit values).
  997.  
  998.     The form 'dim(arrayname, number)' will be replaced by the size of the
  999.     named array in the given dimension (the first dimension is dimension
  1000.     number 1). If the array is a parameter array and the selected dimension
  1001.     was declared as '*', then the value will be obtained at run-time from
  1002.     a hidden parameter passed along with the normal parameters, otherwise,
  1003.     the value is a compile-time constant and can be used in constant
  1004.     expressions. Note that the value is the size of the array in that
  1005.     dimension, which is one greater than the maximum legal index in that
  1006.     dimension.
  1007.  
  1008.     The form 'sizeof(type)' yields a numeric constant which is the number of
  1009.     bytes needed to store an object of the given type. The type can be the
  1010.     name of a declared type, or can be a more complex type description.
  1011.     Proper use of this construct is needed to allow some programs to be
  1012.     portable among machines which have, say, different sized integers. Most
  1013.     programmers will not have to use it, however.
  1014.  
  1015.     The construct 'new(type)' creates a call to the standard storage
  1016.     allocator to allocate a new object of type 'type'. It can be thought of
  1017.     as equivalent to 'pretend(Malloc(sizeof(type)), *type). Note that the
  1018.     value returned is a pointer to the newly allocated storage, and thus its
  1019.     type is *type.
  1020.  
  1021.     The form 'range(type)' can be applied to signed or unsigned numeric types
  1022.     to return the upper limit of that type (the value given when the type was
  1023.     declared); or to an enumeration type to return the number of values in
  1024.     that type. Thus 'range(bool)' is equivalent to '2', and 'range(int)'
  1025.     returns the maximum signed numeric value allowed with the normal integer
  1026.     values supported by that version of the compiler. Note that 'range(byte)'
  1027.     is not legal since 'byte' is not considered to be a normal numeric type,
  1028.     since it is forced to be exactly 1 byte long, regardless of whether that
  1029.     is efficient for the target machine.
  1030.  
  1031. XII. Basic components of Draco programs
  1032.  
  1033.     Identifiers in Draco can be any length. This applies to variables,
  1034.     constants, types and procedure names. The link editor maintains the lack
  1035.     of a limit - the full name of an external procedure is used when
  1036.     searching for it in other files and libraries. Draco treats upper and
  1037.     lower case letters as distinct, thus the identifiers 'A' and 'a' are not
  1038.     the same. The programmer can use any convention he wishes with regard to
  1039.     capitalization, but the conventions mentioned previously are highly
  1040.     recommended. Note also that keywords in Draco are recognized only in the
  1041.     exact case in which they are specified. Identifiers in Draco must start
  1042.     with a letter or an underscore (_), and must consist of letters, digits
  1043.     and underscores.
  1044.  
  1045.     Comments in Draco consist of the delimiters '/*' and '*/' around the
  1046.     portion of the source to be commented out. Comments can span several
  1047.     input lines. Comments can be nested, i.e. a comment entirely within an
  1048.     outer comment is recognized and handled properly by the compiler. Thus, a
  1049.     section of code can be commented out by enclosing it in /* and */,
  1050.     regardless of whether it has any comments in it or not. Comments, along
  1051.     with 'whitespace' (blanks, tabs, carriage-returns and linefeeds) can
  1052.     occur between any two tokens, as well as in string breaks (see below).
  1053.  
  1054.     Numeric constants in Draco can be in decimal, octal, hexadecimal or
  1055.     binary. Simple numbers like '10' and '6348' are treated as decimal. Other
  1056.     bases are selected by preceeding the number by a prefix consisting of a
  1057.     '0' and a base indicator. The base indicators, which can be in upper or
  1058.     lower case, are 'x' for hexadecimal, 'o' for octal, and 'b' for binary.
  1059.     Hexadecimal digits 'a' - 'f' can be in upper or lower case. The compiler
  1060.     checks for proper digits for a given base and for numeric overflow in
  1061.     constants.
  1062.  
  1063.     Character constants in Draco come in two forms. The apostrophe (') is
  1064.     used to delimit single character constants, as in 'a', '.', etc. Quotes
  1065.     (") are used to delimit C - style strings, consisting of a sequence of
  1066.     characters terminated by a 0 character. In both forms, an escape
  1067.     convention is available. The escapes consist of a backslash followed
  1068.     either by a single character, or by a numeric expression enclosed in
  1069.     parentheses. The single character forms are:
  1070.  
  1071.     \b - the ASCII backspace character
  1072.     \t - the ASCII tab character
  1073.     \r - the ASCII carriage return character
  1074.     \n - the ASCII linefeed (newline) character
  1075.     \e - the C - style string termination character (0)
  1076.  
  1077.     Any other character used this way will be passed through unchanged. This
  1078.     can be used to put backslashes and quotation marks of the same type as
  1079.     the delimiter into the string. The convention of doubling a quote mark to
  1080.     produce a single one is also supported. The escape form consisting of a
  1081.     numeric value in parentheses must yield a constant between 0 and 255.
  1082.     This form can be used for special named characters, as in:
  1083.  
  1084.     write('\(BEEP)');        /* ring terminal's bell */
  1085.  
  1086.     The multi-character form of character constants ('chars' values using ")
  1087.     supports the 'string break'. This is a convention which allows a long
  1088.     string to be split up over several input lines, and to be indented
  1089.     nicely. If the last thing (other than spaces, comments, etc.) on an input
  1090.     line is a portion of a chars constant, and the first thing (other than
  1091.     spaces, comments, etc.) on the next input line is a similar constant,
  1092.     then the two are concatenated at compile time to yield a single, longer
  1093.     constant. This can be carried on for as many input lines as are needed to
  1094.     nicely format the constant.
  1095.  
  1096.     Many CP/M systems in use today do not have full ASCII keyboards (e.g.
  1097.     CP/M on the Apple-II or Apple-II+). In such systems, it could be
  1098.     difficult to use Draco, since the language uses characters not found on
  1099.     the keyboards. To help alleviate this problem, the compiler recognizes
  1100.     the following alternate forms for some operators and characters:
  1101.  
  1102.      standard     alternate
  1103.  
  1104.         \            #
  1105.         [            (:
  1106.         ]            :)
  1107.         {            ($
  1108.         }            $)
  1109.         ~=            /=
  1110.         ~            $-
  1111.         |            $/
  1112.         _            ^
  1113.  
  1114.     Draco allows the construction of array and structure constants for
  1115.     named array and structure types. The form is that of a parenthesized
  1116.     list of values. Such constants can be arbitrarily complex. If one is
  1117.     used in a constant declaration, it simply appears after the '='. If one
  1118.     is desired inside executable code, it must be preceeded by the name of
  1119.     the type in question, so that the compiler has some clue as to what is
  1120.     going on. For example:
  1121.  
  1122.     type type1 = struct {int field1, field2; char field3};
  1123.     type type2 = [2] type1;
  1124.     type2 CONST = ((1, 2, 'a'), (3, 4, 'a' - FRED / 2));
  1125.     type2 var;
  1126.     ...
  1127.     var := type2((-26, 13 + 2 / 7, 'a' + 2), (+1, -1, '\e'));
  1128.  
  1129.     The only valid value for pointer types is 'nil'. Union values must be in
  1130.     parentheses like struct values, and must be of the type of the first
  1131.     variant in the union. One special case exists - a one dimensional array
  1132.     of characters can be initialized by a string constant - the constant,
  1133.     including the terminating \e, must not be longer than the dimension of
  1134.     the array. If it is shorter, the array will be padded with \e's.
  1135.  
  1136. XIII. Machine specific constructs
  1137.  
  1138.     The 68000 (Amiga) version of the compiler has several additional features,
  1139.     which can make certain types of programming easier.
  1140.  
  1141.     When a variable (global, file or local) is declared, it can be followed
  1142.     by an '@' and a numeric constant. This informs the compiler that that
  1143.     variable is to be located at that address. This is useful for things
  1144.     like memory-mapped displays and memory-mapped I/O. This same modifier
  1145.     can be appended to 'extern' procedures, enabling Draco programs to call
  1146.     routines at absolute addresses in ROMS.
  1147.  
  1148.     When declaring variables, the value given after the '@' can also be the
  1149.     name of some other variable. In this case, the second named variable must
  1150.     occupy at least as many bytes of storage as the first, and the two will
  1151.     then occupy the same storage. This technique can be used to "type-cheat",
  1152.     but the programmer is strongly advised to use 'pretend' instead, unless
  1153.     unreadable code is desired. This feature of the compiler is intended to
  1154.     be used to conserve storage space as used for variables.
  1155.  
  1156.     Since the Draco compiler directly emits object code, rather than
  1157.     assembler source code, it is not possible to allow in-line assembler
  1158.     language statments. Instead, Draco has the 'code' construct, which
  1159.     consists of the keyword 'code' followed by a parenthesized list of
  1160.     constant expressions and symbol references. The values of constant
  1161.     expressions are emitted directly into the code stream. The type of the
  1162.     constants controls its size as emitted. References to procedures and
  1163.     global or file variables yield 32 bit addresses of them. References to
  1164.     local variables or parameters yield 16 bit stack offsets. (Draco code on
  1165.     the 68000 references locals directly from the stack pointer; a separate
  1166.     "frame pointer" is not used.)
  1167.